Description

Implements StellarError, the last exception in the SDK's typed hierarchy. It wraps the underlying stellar_sdk exception so callers keep access to the raw error while still catching a single SDK type, and exposes Horizon's result codes for programmatic handling.

StellarError(ShadeError) in src/shade/errors.py:

Result codes are read from extras.result_codes, matching stellar_sdk 13.2.1's BaseHorizonError. Messages are built from two lookup tables (transaction + operation codes), preferring the operation-level failure since that is what actually went wrong:

Stellar transaction failed: the destination account has no trustline for the asset
(op_no_trust) (result code: tx_failed) (status code: 400)

Unrecognised codes are passed through raw rather than swallowed. Non-Horizon failures fall back to account_id (for AccountNotFoundException), then Horizon's title/detail, then str(exc).

wrap_stellar_errors() — a context manager covering the issue's third step. The Stellar integration layer wraps its Horizon/Soroban calls with it so callers only ever have to catch ShadeError:

with wrap_stellar_errors("Failed to submit payout txn_123"):
    server.submit_transaction(transaction)

Both are exported from the top-level shade package.

Fixes #35

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

27 new tests in tests/test_stellar_error.py, built against real stellar_sdk exception instances rather than mocks.

• Rejected transactions: transaction and operation result codes, failed_operation_code skipping op_success, Horizon status/body capture, __str__ formatting, fallback to the operation code when no transaction code is present
• Descriptive messages: missing trustline (op_no_trust, op_src_no_trust), underfunded accounts, operation code taking precedence over the transaction code, unrecognised codes passed through raw, explicit message override, title/detail fallback, AccountNotFoundException, non-Horizon SdkError
• original_error exposes the raw exception and is None when constructed directly
• Malformed Horizon payloads: non-dict result_codes, non-list operations, non-string entries — all degrade to "no result codes" instead of raising while building the exception
• wrap_stellar_errors: converts and chains (__cause__), honours the message override, lets non-stellar_sdk exceptions through untouched, transparent on success

Full suite: 277 passed, 3 skipped, no regressions. Both CI flake8 gates clean (--select=E9,F63,F7,F82 and --max-complexity=10 --max-line-length=127).

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Note on scope

The issue's third proposed step says to catch stellar_sdk exceptions "in the Stellar integration layer". That layer (shade/stellar/, FEATURES.md §6) does not exist yet and has no issues filed for it. Rather than build it here, this PR delivers the catching mechanism as wrap_stellar_errors() so that work can simply apply it at each Horizon/Soroban call site. StellarError itself is complete and all three acceptance criteria are met.

Summary by CodeRabbit

• New Features
  • Added clearer Stellar transaction and operation error reporting, including result codes and Horizon response details.
  • Added a context manager for converting Stellar SDK errors into actionable StellarError exceptions.
  • Exposed the new error handling tools through the package’s top-level API.
• Bug Fixes
  • Improved handling of malformed or incomplete error responses without causing additional failures.
  • Preserved non-Stellar exceptions and successful operations unchanged.